Amiga Plus Special 26/AMIGAplus Sonderheft 26 (2000)(Falke)(DE)(Track 1 of 2)[!].iso/Tools/HexED/HexED.doc

Text File | 1999-03-29 | 19KB | 501 lines

-----------------------------------------------------------------------------
                             #   # ##### #   #
                             #   # #      # #
                             ##### ###     #
                             #   # #      # #
                             #   # ##### #   #
-----------------------------------------------------------------------------

                      Hex V1.0, Copyright (c) 1990 by

                             Nicola Salmoria
                             Via Piemonte 11
                             53100 Siena  ITALY

                            All rights reserved.


You can contact me on:
MC-Link:      [phone]      my code is MC6489

Voice:        [phone]

You can try to contact me on FidoNet, but it's unlikely you'll get an answer,
'cos there's yet no Fido node in Siena. Maybe in the future.


This program is SHAREWARE. Copy it as much as you can (provided no charge is
made and the archive is left intact). It can be included, with the same
restrictions, in any commercial program without the written permission of the
author.
Contributions will be greatly appreciated and will help me support Hex in the
future as well as develop new programs. Suggested contribution is $15.
Hex development took 4 months. I spent much time in it, and I'd like to be
rewarded for my work.
Keep one thing in mind: I will probably add new features to Hex, but I will NOT
release a new version until I get enough feedback. So you know what to do.



IMPORTANT NOTE: Hex has some unique features difficult to understand or to
even know about without reading this doc file. If you're too lazy to read it
all, you should read at least the 'Editing & keyboard' chapter, plus the
explanations of the menu items you don't understand.

WARNING: This program in the wrong hands may be a lethal weapon! Use at your
own risk. Anyway, Hex is provided "AS IS", without warranty of any kind, either
expressed or implied. The author will never be liable for any loss of data,
disk damage, computer explosion, earthquake, alien invasion, or anything else.

REMEMBER: It is both immoral and illegal to modify someone else's programs
and redistribute them. All such changes should be considered strictly for
personal use. If you want to let the rest of the world know about some nice
changes you've devised, I think it may be considered acceptable to spread a text
file explaining what to change (like I do with keymaps later on).



--------
Overview
--------

Hex is a file-based (as opposed to sector-based, like NewZAP) binary file
editor. This means that the file is loaded in memory all at once, edited
there and saved at the end. There are advantages and disadvantages in both
approaches: sector-based editors heavy depend on device speed in operations
like search; on the other hand, file based-ones take longer to display the
file for the first time, 'cos they have to load it all. Moreover, file-based
editors need more memory, and it may be impossible to load very large files.
Hex uses the same text routines of MiniView80. This means it's got (one of)
the fastest and smoothest screen rendering ever seen in a file editor.



---------------
Acknowledgement
---------------

I'd like to thank the following people for beta-testing and suggestions:

Federico Giannici
Marco Ciuchini
Antonio Rossi
Massimiliano Marras
Angelo Mariani



-------
Loading
-------

From WorkBench, double-click on Hex icon. You can use extended selection: click
on Hex icon, then press SHIFT and double-click on the file icon.

From CLI, syntax is:
Hex [filename] [NODETACH]
If you specify a file name, it will be loaded on startup.
By default, Hex detaches from the current CLI. You can disable this feature
with the switch NODETACH. It may be useful if you execute Hex from one of that
nice directory utilities.

IMPORTANT NOTE: To load Hex, the file 'req.library' must be in your LIBS:
directory. Req.library is a freely distributable library by C.W.Fox and
Bruce Dawson. If you are a programmer, you may want to take a look at it:
it features the BEST file requester I have ever seen and many other nice
functions.



-----------
The gadgets
-----------

Many hex functions are obtained thru the use of gadgets. Most of them can be
operated also with menus. Of course selecting a menu is less handy than directly
clicking in a gadget; menu operations are there mostly to provide keyboard
shortcuts.

Search gadgets:
---------------
In the 'Search' box there are many gadgets, all obviously related to the search
functions. There are three boxes near to the words 'Search', 'Hex', 'Text'. Only
one of them is selected, and indicates which search mode is currently active.
You can click on them to quickly change search mode.
If a match is found, cursor is placed at the start of it, and edit mode is
changed to the corresponding one.

String
         Search for a given string. Click in the string gadget below and enter
         the text you want to search for. When you press return, search will
         start at cursor position.

A=a
         Search can be case sensitive or case unsensitive; you can switch the
         flag with this gadget.

Hex
         Search for a sequence of bytes you specify via their hexadecimal
         notation. Click in the string gadget below and enter the byte sequence
         you want to search. You can enter data as xx xx xx, xxxxxxxx, xxxx xx
         xxxxxx, anyway you want, provided between two blank spaces there is an
         even number of characters.

CAL
         Imports in the hex gadget the value currently displayed on the
         calculator display. A leading zero is added if needed.

Text
         This is a special feature: it searches the file for occurrencies of at
         least eight 'good' ASCII characters. It is useful to quickly locate
         message strings in a file. When this box is selected, use 'Continue' to
         scan the file.

Continue
         Continues the search from the new cursor position.

<< and >>
         Specify the search direction.


Other gadgets:
--------------
Start and End
         These two behave differently if you are editing a file or GRABbing
         memory (see below). In file mode, 'Start' is always zero and 'End'
         indicates the last byte of the file (or, if you prefer, the file length
         MINUS ONE). In memory mode, they indicate the start and end of the
         memory grabbed. You can change the value contained in these gadgets:
         the file will be modified accordingly, if possible. You can enlarge or
         shrink a file, or change the 'window' on the memory. To add bytes at
         the start of the file, simply insert a negative value. Note that when
         you change the 'Start' gadget in file mode, it is reset to zero and the
         'End' value is changed accordingly.
         If you press SHIFT-Return in one of the gadgets, the other one is
         activated. This is an easy way to change start and end together. It's
         main use is to completely change the portion of memory grabbed.

Position
         Reports the position occupied by the cursor in the file. Modify its
         value to jump to a specific location.

Editing
         Shows which side of the display you are editing: ASCII or HEX. This
         gadget exists only in 'Hex/ASCII' display mode, in 'Only ASCII' it is
         replaced by 'Value', which reports the hex value of the byte the cursor
         is on. You can modify this value, so you don't have to change the
         display mode to insert an hex value in the middle of an ASCII string.

UNDO and REDO
         Self explainatory. Hex features a multi-level undo/redo (currently max
         undo level is 256).



---------
The menus
---------

NOTE: I won't repeat it for every function, but every time you do something
which would mean losing the current data, a requester will appear asking if you
want to save the file, continue anyway, or cancel the operation.

Project:
--------
About
         The usual information about the program.

New
         Creates a new file. The current file is cleared, and the gadget 'End'
         is activated. Type there the size MINUS ONE of the file you want to
         create.

Open
         Loads a new file. The req.library file requester will pop up, asking
         you to select a file to load.

Save
         Saves the file. Again the req.library requester will come, asking the
         filename with which the file will be saved. If you want to overwrite
         the previous version, simply click on OK.

GRAB Memory
         WARNING: this function is dedicated to the expert users.
         The current file is cleared, and the 'Start' gadget activated. Type
         there the start address of the memory you want to grab. If you specify
         a valid number, the 'End' gadget wil activate. Type the end address,
         and there you go!
         Hex will try to AllocAbs() the memory you specify: result of that
         operation is displayed in the menu bar. If the buffer couldn't be
         allocated, the 'Editable file?' flag (see below) is turned off, just to
         provide more protection.
         I deliberately don't check if the memory addresses you specify are
         locations you are allowed to access. I do so to let you GRAB portions
         of memory like system ROMs, expansion ROMs, memory removed from the
         system lists, and so on. For example, (my version of) the A2620 board
         allocates its ROMs at F80000-F87DEF.
         Please note that not only you can crash your system WRITING somewhere
         you shouldn't, but also simply READING some forbidden locations.
         Just to give you an idea, on my system locations between C80000 and
         DFFFFF must be avoided.

Print
         Sends current file to PRT:. If replacement char is '·', it is replaced
         with '.'; char set 'all chars' is not supported, replaced with 'only
         printable'.

Print marked
         Sends to PRT: the portion of the file between the two mark positions.
         It doesn't matter which of the two comes before. Note that the two
         marks are always set somewhere - if you don't initialize them, they
         will point one to the start and the other to the end of the file.

Iconify
         Iconifies Hex. Memory is freed, buffer purged and screen closed - and
         a small window is opened in the WorkBench screen. To reactivate Hex,
         press the right button when that window is active. You can quit
         definitively with the close gadget.

Quit
         Guess what?


Environment:
------------
Palette
         Invokes req.library color requester.

Display
         Two modes are available: Hex/ASCII which prints 16 bytes per row,
         showed in hexadecimal long words and in plain ASCII. Only ASCII prints
         48 bytes per row, only as ASCII characters.

Char set
         Selects which characters should be filtered out in the ASCII dump.
         'All chars' means no substitutions are made; 'Only printable' means
         only chars $20-$7F and $A0-$FF are showed; 'Only $20-$7F' is self
         explanatory.

Replacement char
         Specifies the char with which filtered chars are substituted.
         Choice is between ' ' (space) ,'.' (full stop) and '·' (?? code $B7)

Load settings
         Loads current settings from 'hex.config'.

Save settings
         Saves current settings to 'hex.config'. On future loadings of Hex,
         the saved settings will be automatically re-loaded.
         Settings saved are: Palette, Display, Char set, Replacement char,
         Backspace=undo, Ignore case, Overwrite NULLs, search mode, Iconify
         window position.

Default settings
         Uses the built-in settings.


Edit:
-----
Undo/Redo
         Same as the corresponding gadgets.

Backspace = undo?
         Selects if pressing the backspace key (top right of keyboard) should
         be the same as selecting Undo (or pressing its keyboard shortcut).

Change file start
         All this item does is activate the 'Start' gadget.

Start at cursor pos
         Easy way to make a file begin at the cursor position (instead of
         selecting 'Start', and writing there the correct value).

Change file end
         Activates the 'End' gadget.

End at cursor pos
         Faster way to specify file's end position.

Switch edit mode / Change value
         Same as the corresponding gadgets.

Overwrite NULLs?
         Specifies if in ASCII edit bytes which are zero can be modified.
         When you replace text strings in an executable, e.g. the names of the
         menus, it is VERY important the new strings don't exceed previous
         lengths. Since C strings are NULL-terminated, when this item is
         de-selected, you won't be able to write past the max length allowed.

Editable file?
         If this is not checked, the file cannot be modified in any way. This
         flag is turned OFF when you GRAB a portion of memory which can't be
         allocated; it's turned ON every time the buffer is clear (Load, New)


Search:
-------
Search string
         Activates the 'search string' gadget.

Search hex
         Activates the 'search hex' gadget.

Search text
         Searches for text, as specified before. To continue search, you can use
         'continue' as well as this item again.

Ignore case?
         Switches the case dependancy flag. Equivalent to the 'A=a' gadget.

Direction
         Selects the search direction. Equivalent to the corresponding gadgets.

Continue search
         Repeats last search made. The same as the 'continue' gadget.


Move:
-----
Top
         Jumps to start of file.

Bottom
         Jumps to end of file.

Any position
         Activates the 'position' gadget.

Mark location n
         Set the mark 'n' to the present cursor position. Marks are used also by
         the 'print marked' function.

Jump to mark n
         Jumps to mark 'n'. If the mark wasn't set, jump to start/end of file.




The calculator
--------------

NOTE: on 640x200 screens this feature is not available. NTSC users should usa an
interlaced screen.

On the top right corner of the screen there is a simple calculator. It's use is
fairly simple, being like any usual calculator. I want to point out that you can
use both hte mouse in the intuitive way and the keyboard. In that case, here are
the equivalents to the not-so-intuitive keys:
.                = +/-
$ or H           = Hex
# or T           = Dec
Del or BackSpace = Clear
Help             = On/Off

Moreover, the grey keys on the keypad act as the keys A-F. The same keys SHIFTed
or CAPS LOCKed represent the four operations and the Hex/Dec gadgets. Note that
if you press SHIFT while CAPS LOCK is lit, you get A-F again.


One nice thing to note is that the calculator is a stand-alone task, separated
from the main program; this means it is ALWAYS available, even when Hex is doing
something else like displaying a requester or loading a file from disk.
Another important thing is that the calculator runs on its own window; so don't
panic if when you use it you lose the menus - just click in the main window and
you'll get them back.



Moving around
-------------

There are many ways to move through the file. Clicking on any valid position
will put the cursor there; if you keep the left button pressed and move the
pointer, the cursor will follow you. If you move the pointer to the extreme
top or bottom of screen, you'll scroll through the file. Edit mode changes
correspondingly to where you click.

To fast reach a known position you can use the Jump command or the scroll
bar on the right of the screen.

Using keyboard, cursor keys in combination with shift, alt, ctrl have many
effects. Plain cursor keys move the cursor, and scroll file, in the intuitive
way; shift-up and shift-down move 8 positions at a time and scroll faster;
alt-up and alt-down move one page at a time; any qualifier together with
left/right moves to begin/end of current line. Ctrl-up and ctrl-down move to
start and end of file.




Editing & keyboard
------------------

In ASCII edit, simply type what you like. Note that Return generates a LF ($0A),
while Enter a CR ($0D). Moreover, SHIFT-Return generates a NULL. This is very
useful to terminate strings without having to switch to HEX edit.
In HEX edit, type couples of hex chars. If you mistake the first number,
SPACE will cancel it. Please note that you won't see the first number you
type: only the full byte is substituded after you enter the couple of chars.

Hex uses RawKeyConvert(), so custom keymaps ARE supported.
There is an exception: while in hex edit, grey keys on the numeric keypad
behave like keys A-F. This allows very fast input of data. This is the layout
of the keypad:

       +-----+-----+-----+-----+
       |     |     |     |     |
       |  A  |  B  |  C  |  D  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  7  |  8  |  9  |  E  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  4  |  5  |  6  |  F  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  1  |  2  |  3  |  E  |
       |     |     |     |  n  |
       +-----+-----+-----+  t  |
       |           |     |  e  |
       |     0     |  .  |  r  |
       |           |     |     |
       +-----------+-----+-----+

Such feature would be handy also in the input gadgets; however, they are handled
by Intuition, so a keymap is needed. I have provided a file called 'h', which is
a custom keymap you should put in DEVS:keymaps.
However, if you like, you can modify your keymap and use it with hex or anywhere
you like. Here is how to proceed:

- Load Hex (this is the least you could expect!).
- OPEN DEVS:keymaps/your_keymap.
- JUMP to 20F. There should be a '-' there.
- Modify the '-' to 'E'.
- JUMP to 24F. This is the top-left key in the keypad.
- Modify it to 'A'.
- Go to 253. Modify to 'B'.
- Go to 257. Modify to 'C'.
- Go to 25B. Modify to 'D'.
- Go to 25F. Modify to 'F'.
- SEARCH for '?~'. After these two chars, there should be the name of the
  keyboard. Replace it with 'h'. If the keymap name is longer then one char,
  remember to put a NULL after h.
- SAVE as DEVS:keymaps/h

All done. Hex will automatically load DEVS:keymaps/h on startup.




Note about requesters
---------------------

You don't need mouse to reply to req.library requesters. There's a whole
range of keys you can use, the easiest to remember are:
L for the left gadget
M for the middle gadget
R for the right gadget